home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 22 / CU Amiga Magazine's Super CD-ROM 22 (1998)(EMAP Images)(GB)[!][issue 1998-05].iso / PowerPC / System / PPCReleaseDEV / FD2Inline / fd2inline.guide < prev    next >
Encoding:
GNU Info File  |  1998-02-21  |  30.1 KB  |  811 lines
  1. This is Info file fd2inline.guide, produced by Makeinfo-1.64 from the
  2. input file ./fd2inline.texi.
  3.  
  4.    This is a user's guide to FD2Inline 1.11, a parser converting FD
  5. files to GCC "inlines".
  6.  
  7.    Copyright (C) 1996, 1997 Kamil Iskra
  8.  
  9.    Permission is granted to make and distribute verbatim copies of this
  10. manual provided the copyright notice and this permission notice are
  11. preserved on all copies.
  12.  
  13. 
  14. File: fd2inline.guide,  Node: Top,  Next: Introduction,  Prev: (dir),  Up: (dir)
  15.  
  16.    This is a user's guide to `FD2Inline' 1.11, a parser that converts
  17. the AmigaOS shared library `FD' files to format accepted by the `GNU
  18. CC'.
  19.  
  20.    See file `COPYING' for the GNU General Public License.
  21.  
  22.    Last updated January 31st, 1997.
  23.  
  24. * Menu:
  25.  
  26. * Introduction::  What is this program for?
  27. * Installation::  How to install it?
  28. * Usage::         How to use `inlines' and `FD2InLine'?
  29. * Rebuilding::    How to recompile it?
  30. * Internals::     How do `inlines' work?
  31. * History::       What has changed?
  32. * Authors::       Who wrote it?
  33.  
  34. * Index::         Concept index.
  35.  
  36. 
  37. File: fd2inline.guide,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top
  38.  
  39. Introduction
  40. ************
  41.  
  42.    `FD2InLine' is useful if you want to use `GCC' for AmigaOS-specific
  43. development and would like to call the functions in the AmigaOS shared
  44. libraries efficiently.
  45.  
  46.    The format of calls to the AmigaOS shared library functions differs
  47. substantially from the default function call format of C compilers
  48. (*note Background::.). Therefore, some tricks are necessary if you want
  49. to use these functions.
  50.  
  51.    `FD2InLine' is a parser that converts `fd' files and `clib' files to
  52. `GCC inlines'.
  53.  
  54.    `fd' and `clib' files contain information about functions in shared
  55. libraries (*note Background::.).
  56.  
  57.    `FD2InLine' reads these two files and merges the information
  58. contained therein, producing an output file suitable for use with the
  59. `GCC' compiler.
  60.  
  61.    This output file contains so-called "inlines" -- one for each
  62. function entry. Using them, `GCC' can produce very efficient code for
  63. making function calls to the AmigaOS shared libraries.
  64.  
  65.      *Note:* the term `inlines' is misleading -- `FD2InLine' no longer
  66.      uses the `__inline' feature of `GCC' (*note New format::.).
  67.  
  68. 
  69. File: fd2inline.guide,  Node: Installation,  Next: Usage,  Prev: Introduction,  Up: Top
  70.  
  71. Installation
  72. ************
  73.  
  74.    The following assumes you have the `fd2inline-1.11-bin.lha' archive.
  75.  
  76.    If you use a recent release of `GCC', you might not need to install
  77. anything. Starting with `GCC' 2.7.2, the new format (*note New
  78. format::.) of `inlines' should be available with the compiler. However,
  79. the separate `fd2inline-1.11-bin.lha' archive will always contain the
  80. latest version of `FD2InLine' and the `inlines', which might not be the
  81. true for the `Geek Gadgets' or `Aminet' distributions. `Geek Gadgets'
  82. distribution might not contain some of the supported 3rd party
  83. libraries' `inlines'.
  84.  
  85.    The installation is very easy, so there is no Installer script :-).
  86.  
  87.    If you have an older version of the `inlines' installed, please
  88. remove it now, or you might encounter problems later. Typically, you
  89. will have to remove the following subdirectories of the `os-include'
  90. directory: `inline', `pragmas' and `proto'.
  91.  
  92.    Next, please change your current directory to `GG:' (or `GNU:', if
  93. you use old `Aminet' release) and simply unpack the
  94. `fd2inline-1.11-bin.lha' archive. This should install everything in the
  95. right place. More precisely, the headers will go to the `include'
  96. directory, the libraries to `lib', `fd2inline' executable to `bin'
  97. directory and the `AmigaGuide' documentation to the `guide' directory.
  98.  
  99. 
  100. File: fd2inline.guide,  Node: Usage,  Next: Rebuilding,  Prev: Installation,  Up: Top
  101.  
  102. Usage
  103. *****
  104.  
  105.    This chapter describes two aspects of using `FD2InLine':
  106.  
  107. * Menu:
  108.  
  109. * Using inlines::    Making efficient function calls.
  110. * Using fd2inline::  Creating `inlines'.
  111.  
  112. 
  113. File: fd2inline.guide,  Node: Using inlines,  Next: Using fd2inline,  Prev: Usage,  Up: Usage
  114.  
  115. Using inlines
  116. =============
  117.  
  118.    Using `inlines' is very simple. If you want to use a library called
  119. `foo.library' (or a device called `bar.device'), simply include file
  120. `<proto/foo.h>' (`<proto/bar.h>') and that's it. For example:
  121.  
  122.      #include <proto/dos.h>
  123.      
  124.      int main(void)
  125.      {
  126.         Delay(100); /* Wait for 2 seconds */
  127.      }
  128.  
  129.    Please *always* include `proto' files, *not* `inline' files -
  130. `proto' files often fix some incompatibilities between system headers
  131. and `GCC'. Besides, this technique makes your code more portable across
  132. various AmigaOS `C' compilers.
  133.  
  134.    There are a few preprocessor symbols which alter the behaviour of the
  135. `proto' and `inline' files:
  136.  
  137. `__NOLIBBASE__'
  138.      By default, the `proto' files make external declarations of the
  139.      library base pointers. You can disable this behaviour by defining
  140.      `__NOLIBBASE__' before including a `proto' file.
  141.  
  142. `__CONSTLIBBASEDECL__'
  143.      The external declarations described above declare plain pointer
  144.      variables. The disadvantage of this is that the library base
  145.      variable has to be reloaded every time some function is called. If
  146.      you define `__CONSTLIBBASEDECL__' to `const', less reloading will
  147.      be necessary, and better code will be produced. However, declaring
  148.      a variable as `const' makes altering it impossible, so some dirty
  149.      hacks are necessary (like defining the variable as plain in one
  150.      file and altering it only there. However, this will *not* work with
  151.      base relative code).
  152.  
  153. `<library>_BASE_NAME'
  154.      Function definitions in the `inline' files refer to the library
  155.      base variable through the `<library>_BASE_NAME' symbol (e.g.,
  156.      `AMIGAGUIDE_BASE_NAME' for `amigaguide.library'). At the top of
  157.      the `inline' file, this symbol is redefined to the appropriate
  158.      library base variable name (e.g., `AmigaGuideBase'), *unless* it
  159.      has been already defined. This way, you can make the `inlines' use
  160.      a field of a structure as a library base, for example.
  161.  
  162. `NO_INLINE_STDARG'
  163.      This symbol prevents the definition of inline macros for varargs
  164.      functions (*note Old format::.).
  165.  
  166. `_USEOLDEXEC_'
  167.      This symbol is used only in `proto/exec.h'. Unlike `SAS/C',
  168.      `proto/exec.h' uses the `SysBase' variable as the `Exec' library
  169.      base by default. This is usually faster than direct dereferencing
  170.      of `0x00000004' (*note Background::.), since it does not require
  171.      reading from `CHIP' memory (things might be even worse if you use
  172.      `Enforcer' or `CyberGuard', which protect the low memory region).
  173.      However, in some low-level cases (like startup code) you might
  174.      prefer dereferencing `0x00000004'. To do this, define
  175.      `_USEOLDEXEC_' before including `proto/exec.h'.
  176.  
  177. 
  178. File: fd2inline.guide,  Node: Using fd2inline,  Prev: Using inlines,  Up: Usage
  179.  
  180. Using fd2inline
  181. ===============
  182.  
  183.    You invoke `FD2InLine' by writing:
  184.  
  185.      `fd2inline' [options] FD-FILE CLIB-FILE [[-o] OUTPUT-FILE]
  186.  
  187.    The command line arguments have the following meaning:
  188.  
  189. FD-FILE
  190.      The name of the input `fd' file.
  191.  
  192. CLIB-FILE
  193.      The name of the input `clib' file.
  194.  
  195. OUTPUT-FILE
  196.      The name of the output `inline' file. If it is not specified (or
  197.      if `-' is specified), standard output will be used instead. The
  198.      file name can be preceded by a `-o', for compatibility with most
  199.      `UN*X' software.
  200.  
  201.    The following options can be specified (anywhere on the command
  202. line):
  203.  
  204. `--new'
  205.      Produce new format `inlines'.
  206.  
  207. `--old'
  208.      Produce old format `inlines'.
  209.  
  210. `--stubs'
  211.      Produce library stubs.
  212.  
  213. `--proto'
  214.      Produce `proto' file. If this option is specified, providing
  215.      `clib' file is not necessary. `fd2inline' will only read `fd' file
  216.      and will generate a `proto' file, to be put in `include/proto'
  217.      directory.
  218.  
  219. `--version'
  220.      Print version information and exit.
  221.  
  222.    *Note Internals::, for more information.
  223.  
  224.    Example:
  225.  
  226.      fd2inline GG:os-lib/fd/exec_lib.fd GG:os-include/clib/exec_protos.h -o GG:include/inline/exec.h
  227.  
  228.    This will build file `exec.h' containing new format `inlines' of
  229. `exec.library' in directory `GG:include/inline'.
  230.  
  231.    If you want to add support for `GCC' to a library, there are a few
  232. things you should remember about.
  233.  
  234.    Sometimes, `FD2InLine' might not know how to handle a function found
  235. in a `clib' file, if this function doesn't have a corresponding entry
  236. in the `fd' file. This is most often a case of `varargs' functions
  237. (*note Background::.), if they use nonstandard naming convention.
  238. `FD2InLine' will warn you if it finds such a function. There is an
  239. array of such exceptions in `FD2InLine' source code. You should add the
  240. name of this function there and send a patch to `FD2InLine' maintainer
  241. (*note Authors::.), for inclussion in the next release of `FD2InLine'.
  242.  
  243.    `FD2InLine' assumes that the type of the base variable is `struct
  244. Library *'. If it is something different in your case, you should
  245. extend an array of exceptions in `FD2InLine' source code (see above).
  246.  
  247.    `FD2InLine' handles `void' functions in a special way. It recognizes
  248. them by the return value -- it has to be `void' (the case is not
  249. significant). If a `clib' file uses a different convention, it has to
  250. be modified before running `FD2InLine'.
  251.  
  252.    In addition to creating `inlines' you must also create a `proto'
  253. file.
  254.  
  255.    The easiest way to do it is to call `FD2InLine' with `--proto'
  256. option. Most often, the generated file will be ready to use.
  257. Unfortunately, some libraries (like, for example, `dos.library') have
  258. broken header files and `GCC' generates warning messages if you try to
  259. use them. To avoid these warnings, you have to include various headers
  260. in the `proto' file before including the `clib' file.
  261.  
  262.    You might also want to create a `pragmas' file, which might be
  263. necessary for badly written `SAS/C' sources. `pragmas' are generated
  264. automatically during the building of `FD2InLine' by an `AWK' script, so
  265. you might either have a look at the `fd2inline-1.11-src.lha' archive,
  266. or simply create `pragmas' file by hand.
  267.  
  268.    Creating a linker library with stubs might also be useful, in case
  269. somebody doesn't want to, or can't, use inline headers.
  270.  
  271.    `fd2inline-1.11-src.lha' contains necessary support for this. For
  272. example, to generate a library `libexec.a' with `exec.library' stubs,
  273. you should type:
  274.  
  275.      make alllib INCBASE=exec LIBBASE=exec
  276.  
  277.    This will create three `libexec.a' libraries in `lib' subdirectory:
  278. plain, base relative and 32-bit base relative one. Of course, this
  279. particular example doesn't make much sense since `libamiga.a' already
  280. contains these stubs.
  281.  
  282.    `INCBASE' and `LIBBASE' specify the base names of the (input)
  283. `proto' and `fd' files and the (output) library.  This will often be
  284. the same, but not always. For example, in the case of `MUI', `INCBASE'
  285. has to be set to `muimaster', but `LIBBASE' should be set to `mui'.
  286.  
  287. 
  288. File: fd2inline.guide,  Node: Rebuilding,  Next: Internals,  Prev: Usage,  Up: Top
  289.  
  290. Rebuilding
  291. **********
  292.  
  293.    First, you have to get the `fd2inline-1.11-src.lha' archive.
  294.  
  295.    Unarchive it. You might either build `FD2InLine' in source directory
  296. or in a separate, build directory. The latter is recommended. Type:
  297.  
  298.      lha -mraxe x fd2inline-1.11-src.lha
  299.      mkdir fd2inline-bin
  300.      cd fd2inline-bin
  301.      sh ../fd2inline-1.11/configure --prefix=/gg
  302.      make
  303.  
  304.    This should build the `FD2InLine' executable, headers, libraries and
  305. so on.
  306.  
  307.    Please note that the `fd' files should be available in the directory
  308. `GG:os-lib/fd'. If you store them in some other place, you will have to
  309. edit the `Makefile' and modify variable `FD_DIR' before invoking `make'.
  310.  
  311.    You can then type:
  312.  
  313.      make install
  314.  
  315.    This will install `fd2inline', the `inlines' and the documentation
  316. in the appropriate subdirectories of `GG:'.
  317.  
  318.    The `fd2inline-1.11-src.lha' archive contains four patches in
  319. unified diff format, in directory `patches'. They fix bugs in OS 3.1
  320. headers and `fd' files. Without applying `amigaguide_lib.fd.diff' to
  321. `amigaguide.library' `fd' file, the produced `inlines' will be broken.
  322. Applying `timer.h.diff' to `devices/timer.h' will prevent collision
  323. with IXEmul's `sys/time.h'. Two other patches rename an argument name
  324. from `true' to `tf', since `true' is a reserved word in `C++'. Use
  325. `patch' to apply these patches, for example:
  326.  
  327.      cd GG:os-lib/fd
  328.      patch -p0 <amigaguide_lib.fd.diff
  329.  
  330.    `Geek Gadgets' and `Aminet' distributions contain more complete sets
  331. of patches.
  332.  
  333.    A few words about the source code:
  334.  
  335.    I know, it's not state-of-the-art `C' programming example.  However,
  336. believe me, it was in *much* worse condition when I took it over. In
  337. its current state it is at least readable (if you use tab size 3, as I
  338. do :-). I think that rewriting it in `C++' would clean it up
  339. considerably (it's already written in `OO' fashion, so this should be
  340. quite easy). Using `flex' and `bison' to create the parser would also
  341. be a nice thing, I guess. However, I don't think it's worth the effort.
  342. But, if somebody wants to do it: feel free, this is `GNU' software, so
  343. everybody can modify it.
  344.  
  345. 
  346. File: fd2inline.guide,  Node: Internals,  Next: History,  Prev: Rebuilding,  Up: Top
  347.  
  348. Internals
  349. *********
  350.  
  351.    This chapter describes the implementation details of `inlines'.
  352.  
  353. * Menu:
  354.  
  355. * Background::    Function calls in shared libraries.
  356. * Old format::    Inlines that use `__inline'.
  357. * New format::    Inlines that use the preprocessor.
  358. * Stubs format::  Not really inlines, but...
  359.  
  360. 
  361. File: fd2inline.guide,  Node: Background,  Next: Old format,  Prev: Internals,  Up: Internals
  362.  
  363. Background
  364. ==========
  365.  
  366.    This section describes the calling conventions used in the AmigaOS
  367. shared libraries.
  368.  
  369.    User-callable functions in the AmigaOS are organized in "libraries".
  370.  
  371.    From our point of view, the most important part of a library is the
  372. "library base". It always resides in RAM and contains library variables
  373. and a "jump table". The location of the library base varies. You can
  374. obtain the library base location of the main system library --
  375. `exec.library' -- by dereferencing `0x00000004'. Locations of other
  376. library bases can be obtained using the `OpenLibrary' function of
  377. `exec.library'.
  378.  
  379.    Without providing unnecessary details, every function in a library
  380. has a fixed location in the library's jump table. To call a function,
  381. one has to jump to this location.
  382.  
  383.    Most functions require some arguments. In `C', these are usually
  384. passed on the CPU stack. However, for some obscure reason, AmigaOS
  385. system designers decided that arguments to shared libraries should be
  386. passed in CPU registers.
  387.  
  388.    All the information required to make library function calls is
  389. provided in "fd" files. Every shared library should have such a file.
  390. It provides the name a library base variable should have, the offset in
  391. the jump table where each library function resides, and information
  392. about which arguments should be passed in which registers.
  393.  
  394.    In order to check if arguments passed to a function have the correct
  395. type, the `C' compiler requires function prototypes. These are provided
  396. in "clib" files -- every library should have such a file.
  397.  
  398.    Starting with the AmigaOS release 2.0, certain functions have been
  399. provided which accept a variable number of arguments (so-called
  400. "varargs functions"). Actually, these are only `C' language stubs.
  401. Internally, all optional arguments have to be put into an array of
  402. `long ints' and the address of this array must be passed to a fixed
  403. args library function.
  404.  
  405.    To implement calls to shared library functions, compiler vendors have
  406. to either use some compiler-dependent tricks to make these calls
  407. directly (so-called "in line"), or provide linker libraries with
  408. function stubs, usually written in assembler. In the latter case, a
  409. function call from the user's code is compiled as usual -- arguments
  410. are passed on the stack. Then, in the linking stage, a library stub
  411. gets linked in. When this stub is called during program execution, it
  412. moves the arguments from the stack to the appropriate registers and
  413. jumps to the library jump table. Needless to say, this is slower than
  414. making a call in line.
  415.  
  416. 
  417. File: fd2inline.guide,  Node: Old format,  Next: New format,  Prev: Background,  Up: Internals
  418.  
  419. Old format
  420. ==========
  421.  
  422.      extern __inline APTR
  423.      OpenAmigaGuideA(BASE_PAR_DECL struct NewAmigaGuide *nag, struct TagItem *attrs)
  424.      {
  425.         BASE_EXT_DECL
  426.         register APTR res __asm("d0");
  427.         register struct Library *a6 __asm("a6") = BASE_NAME;
  428.         register struct NewAmigaGuide *a0 __asm("a0") = nag;
  429.         register struct TagItem *a1 __asm("a1") = attrs;
  430.         __asm volatile ("jsr a6@(-0x36:W)"
  431.         : "=r" (res)
  432.         : "r" (a6), "r" (a0), "r" (a1)
  433.         : "d0", "d1", "a0", "a1", "cc", "memory");
  434.         return res;
  435.      }
  436.  
  437.    In this implementation, the AmigaOS shared library function stubs are
  438. external functions. They are defined as `__inline', making `GCC' insert
  439. them at every place of call. The mysterious `BASE_PAR_DECL' and
  440. `BASE_EXT_DECL' defines are hacks necessary for local library base
  441. support (which is quite hard to achieve, so it will not be described
  442. here). The biggest disadvantage of these `inlines' is that compilation
  443. becomes very slow, requiring huge amounts of memory. Besides, inlining
  444. only works with optimization enabled.
  445.  
  446.      #ifndef NO_INLINE_STDARG
  447.      #define OpenAmigaGuide(a0, tags...) \
  448.         ({ULONG _tags[] = { tags }; OpenAmigaGuideA((a0), (struct TagItem *)_tags);})
  449.      #endif /* !NO_INLINE_STDARG */
  450.  
  451.    The source above shows how `varargs' functions are implemented.
  452. Handling them cannot be made using `__inline' functions, since
  453. `__inline' functions require a fixed number of arguments.  Therefore,
  454. the unique features of the `GCC' preprocessor (such as `varargs
  455. macros') have to be used, instead. This has some drawbacks,
  456. unfortunately. Since these are actually preprocessor macros and not
  457. function calls, you cannot make tricky things involving the
  458. preprocessor inside them. For example:
  459.  
  460.      #include <proto/amigaguide.h>
  461.      
  462.      #define OPENAG_BEG OpenAmigaGuide(
  463.      #define OPENAG_END , TAG_DONE)
  464.      
  465.      void f(void)
  466.      {
  467.         OPENAG_BEG "a_file.guide" OPENAG_END;
  468.         OpenAmigaGuide(
  469.      #ifdef ABC
  470.            "abc.guide",
  471.      #else
  472.            "def.guide",
  473.      #endif
  474.            TAG_DONE);
  475.      }
  476.  
  477.    Neither of the above `OpenAmigaGuide()' calls is handled correctly.
  478.  
  479.    In the case of the first call, you get an error:
  480.  
  481.      unterminated macro call
  482.  
  483.    By the time the preprocessor attempts to expand the `OpenAmigaGuide'
  484. macro, `OPENAG_END' is not yet expanded, so the preprocessor cannot
  485. find the closing bracket. This code might look contrived, but `MUI',
  486. for example, defines such macros to make code look more pretty.
  487.  
  488.    In the case of the second call, you'll see:
  489.  
  490.      warning: preprocessing directive not recognized within macro arg
  491.  
  492.    A workaround would be to either surround entire function calls with
  493. conditions, or to conditionally define a preprocessor symbol `GUIDE'
  494. somewhere above and simply put `GUIDE' as a function argument:
  495.  
  496.      #ifdef ABC
  497.      #define GUIDE "abc.guide"
  498.      #else
  499.      #define GUIDE "def.guide"
  500.      #endif
  501.      
  502.      void f(void)
  503.      {
  504.      #ifdef ABC
  505.         OpenAmigaGuide("abc.guide", TAG_DONE);
  506.      #else
  507.         OpenAmigaGuide("def.guide", TAG_DONE);
  508.      #endif
  509.         OpenAmigaGuide(GUIDE, TAG_DONE);
  510.      }
  511.  
  512.    Another problem is that when you pass a pointer as an argument, you
  513. get a warning:
  514.  
  515.      warning: initialization makes integer from pointer without a cast
  516.  
  517.    This is because all optional arguments are put as initializers to an
  518. array of `ULONG'. And, if you attempt to initialize an `ULONG' with a
  519. pointer without a cast, you get a warning. You can avoid it by explicit
  520. casting of all pointer arguments to `ULONG'.
  521.  
  522.    Because of these drawbacks, `varargs inlines' can be disabled by
  523. defining `NO_INLINE_STDARG' before including a `proto' file.  In such a
  524. case, you will need a library with function stubs.
  525.  
  526. 
  527. File: fd2inline.guide,  Node: New format,  Next: Stubs format,  Prev: Old format,  Up: Internals
  528.  
  529. New format
  530. ==========
  531.  
  532.      #define OpenAmigaGuideA(nag, attrs) \
  533.         LP2(0x36, APTR, OpenAmigaGuideA, struct NewAmigaGuide *, nag, a0, struct TagItem *, attrs, a1, \
  534.         , AMIGAGUIDE_BASE_NAME)
  535.  
  536.    As you can see, this implementation is much more compact. The `LP2'
  537. macro (and others) are defined in `inline/macros.h', which is included
  538. at the beginning of every `inline' file.
  539.  
  540.      #define LP2(offs, rt, name, t1, v1, r1, t2, v2, r2, bt, bn) \
  541.      ({                            \
  542.         t1 _##name##_v1 = (v1);                \
  543.         t2 _##name##_v2 = (v2);                \
  544.         {                            \
  545.            register rt _##name##_re __asm("d0");        \
  546.            register struct Library *const _##name##_bn __asm("a6") = (struct Library*)(bn);\
  547.            register t1 _n1 __asm(#r1) = _##name##_v1;    \
  548.            register t2 _n2 __asm(#r2) = _##name##_v2;    \
  549.            __asm volatile ("jsr a6@(-"#offs":W)"        \
  550.            : "=r" (_##name##_re)                \
  551.            : "r" (_##name##_bn), "r"(_n1), "r"(_n2)        \
  552.            : "d0", "d1", "a0", "a1", "cc", "memory");    \
  553.            _##name##_re;                    \
  554.         }                            \
  555.      })
  556.  
  557.    If you compare this with the old `inlines' (*note Old format::.) you
  558. will notice many similarities. Indeed, both implementations use the
  559. same tricks. This means that there should be small, if any, difference
  560. in code quality between old and new `inlines'.
  561.  
  562.    With the new `inlines', however, inlining is performed very early,
  563. at the preprocessing stage. This makes compilation much faster, less
  564. memory hungry, and independent of the optimization options used.  This
  565. also makes it very easy to use local library bases -- all that is
  566. needed is to define a local variable with the same name as library base.
  567.  
  568.    Unfortunately, using the preprocessor instead of the compiler for
  569. making function calls has its drawbacks, as described earlier (*note
  570. Old format::.). There is not much you can do about it apart from
  571. modifying your code.
  572.  
  573.    Depending on the type of a function, `FD2InLine' generates calls to
  574. different `LP' macros.
  575.  
  576.    Macros are distinguished by one or more of the qualifiers described
  577. below:
  578.  
  579. `digit'
  580.      As you may have already guessed, digit indicates the number of
  581.      arguments a function accepts. Therefore, it is mandatory.
  582.  
  583. `NR'
  584.      This indicates a "no return" (`void') function.
  585.  
  586. `A4, A5'
  587.      These two are used when one of the arguments has to be in either
  588.      the `a4' or `a5' register. In certain situations, these registers
  589.      have special meaning and have to be handled more carefully.
  590.  
  591. `UB'
  592.      This indicates "user base" -- the library base pointer has to be
  593.      specified explicitly by the user. Currently, this is used for
  594.      `cia.resource' only. Since there are two `CIA' chips, the
  595.      programmer has to specify which one [s]he wants to use.
  596.  
  597. `FP'
  598.      This means that one of the arguments is of type "pointer to a
  599.      function". To overcome strange `C' syntax rules in this case,
  600.      inside `FP' macros a `typedef' to `__fpt' is performed.  The
  601.      `inline' file passes `__fpt' as the argument type to the `LP'
  602.      macro. The actual type of the argument, in a form suitable for a
  603.      `typedef', is passed as an additional, last argument.
  604.  
  605.    As you can see, there could be more than a hundred different
  606. variations of the `LP' macros. `inline/macros.h' contains only 34,
  607. which are used in the current OS version and supported 3rd party
  608. libraries. More macros will be added in the future, if needed.
  609.  
  610.    If you look carefully at the definition of `OpenAmigaGuideA' at the
  611. beginning of this section, you might notice that the next to last
  612. argument to the `LP' macro is not used. New `inlines' were not
  613. implemented in one evening, and they went through many modifications.
  614. This unused argument (which was once a type of library base pointer) is
  615. provided for backwards compatibility. Actually, there are more
  616. unnecessary arguments, like function and argument names, but it was
  617. decided to leave them in peace.
  618.  
  619. 
  620. File: fd2inline.guide,  Node: Stubs format,  Prev: New format,  Up: Internals
  621.  
  622. Stubs format
  623. ============
  624.  
  625.    Stubs format is very similar to old format (*note Old format::.). The
  626. functions are not defined as `extern', however.
  627.  
  628.    The main difference is the format of the `varargs' functions -- they
  629. are plain functions, not preprocessor macros.
  630.  
  631.      APTR OpenAmigaGuide(struct NewAmigaGuide *nag, int tag, ...)
  632.      {
  633.         return OpenAmigaGuideA(nag, (struct TagItem *)&tag);
  634.      }
  635.  
  636.    This format is not suitable for inlining, and it is not provided for
  637. this purpose. It is provided for the building of linker libraries with
  638. stubs (*note Using fd2inline::.).
  639.  
  640. 
  641. File: fd2inline.guide,  Node: History,  Next: Authors,  Prev: Internals,  Up: Top
  642.  
  643. History
  644. *******
  645.  
  646.    Version 1.0,  July 14th, 1996,  Kamil Iskra
  647.    * First officially available version.
  648.  
  649.    Version 1.1,  October 24th, 1996,  Kamil Iskra
  650.    * Removed a lot of language mistakes from the documentation (Kriton
  651.      Kyrimis).
  652.  
  653.    * Inlines of `dospath.library', `screennotify.library',
  654.      `ums.library' and `wbstart.library' integrated (Martin
  655.      Steigerwald).
  656.  
  657.    * Inlines of `muimaster.library' integrated (Kamil Iskra).
  658.  
  659.    * Floating point registers `fp0' and `fp1' are now marked as
  660.      clobbered (Kamil Iskra, reported by Kriton Kyrimis).
  661.  
  662.    * Improved handling of `clib' files, particularly recognition of
  663.      function prototypes and varargs functions (Kamil Iskra).
  664.  
  665.    * Added support for `--proto' and `--version' options. Minor changes
  666.      in output file generators, most notably making `proto' files work
  667.      with other compilers than `GCC', too. Finalized support for
  668.      building linker libraries (Kamil Iskra, change in `proto' files
  669.      suggested by Joop van de Wege).
  670.  
  671.    Version 1.11,  January 31st, 1997,  Kamil Iskra
  672.    * Minor fixes in `Makefile.in' for `Geek Gadgets' tree (Fred Fish).
  673.  
  674.    * Fixed handling of prototypes in which the argument name was the
  675.      same as the type name (Kamil Iskra, reported by Martin
  676.      Recktenwald).
  677.  
  678.    * Added support for building 32-bit base relative linker libraries
  679.      (Kamil Iskra).
  680.  
  681.    * Added a paragraph about `void' functions (Kamil Iskra, suggested
  682.      by Martin Recktenwald).
  683.  
  684. 
  685. File: fd2inline.guide,  Node: Authors,  Next: Index,  Prev: History,  Up: Top
  686.  
  687. Authors
  688. *******
  689.  
  690.    The first parser for `GCC inlines' was written in `Perl' by Markus
  691. Wild.
  692.  
  693.    It had several limitations, which were apparently hard to fix in
  694. `Perl'. This is why Wolfgang Baron decided to write a new parser in `C'.
  695.  
  696.    For some reason, however, he never finished it. In early 1995. Rainer
  697. F. Trunz took over its development and "improved, updated, simply made
  698. it workable" (quotation from the change log). It still contained quite
  699. a few bugs, though.
  700.  
  701.    In more-or-less the same time, I started a discussion on the
  702. `amiga-gcc-port' mailing list about improving the quality of `inlines'.
  703. The most important idea came from Matthias Fleischer, who introduced
  704. the new format of `inlines' (*note New format::.).  Since I started the
  705. discussion, I volunteered to make improvements to the `inlines' parser.
  706. Having no idea about programming in `Perl', I decided to modify the
  707. parser written in `C'. I fixed all the bugs known to me, added some new
  708. features, and wrote this terribly long documentation :-).
  709.  
  710.    Not all of the files distributed in the `FD2InLine' archives were
  711. created by me or `FD2InLine'. Most of the files in `include/proto-src'
  712. and `include/inline-src' (`alib.h', `strsub.h' and `stubs.h') were
  713. written by Gunther Nikl (with some modifications by Joerg Hoehle and
  714. me).
  715.  
  716.    If you have any comments concerning this work, please write to:
  717.  
  718.    gg-gcc@ninemoons.com
  719.  
  720.    This is a list to which most of the `Geek Gadgets GCC' developers and
  721. activists subscribe, so you are practically guaranteed to get a reply.
  722.  
  723.    However, if, for some reason, you want to contact me personally, you
  724. can do so in one of the following ways:
  725.  
  726.    * E-mail (preferred :-):
  727.  
  728.      iskra@student.uci.agh.edu.pl
  729.  
  730.      Should be valid until October 1999 (at least I hope so :-).
  731.  
  732.    * Snail-mail (expect to wait long for a reply :-):
  733.  
  734.      Kamil Iskra
  735.      Luzycka 51/258
  736.      30-658 Krakow
  737.      Poland
  738.  
  739.    Latest version of this package should always be available on my WWW
  740. page:
  741.  
  742. http://student.uci.agh.edu.pl/~iskra
  743.  
  744. 
  745. File: fd2inline.guide,  Node: Index,  Prev: Authors,  Up: Top
  746.  
  747. Index
  748. *****
  749.  
  750. * Menu:
  751.  
  752. * <library>_BASE_NAME:                  Using inlines.
  753. * __CONSTLIBBASEDECL__:                 Using inlines.
  754. * __NOLIBBASE__:                        Using inlines.
  755. * _USEOLDEXEC_:                         Using inlines.
  756. * Address:                              Authors.
  757. * Authors:                              Authors.
  758. * Background:                           Background.
  759. * CLIB files:                           Background.
  760. * Creating inlines:                     Using fd2inline.
  761. * FD files:                             Background.
  762. * Function arguments:                   Background.
  763. * Function calls format in shared libraries: Background.
  764. * History:                              History.
  765. * Installation:                         Installation.
  766. * Internals:                            Internals.
  767. * Introduction:                         Introduction.
  768. * Jump table:                           Background.
  769. * Latest version:                       Authors.
  770. * Libraries:                            Background.
  771. * Library base:                         Background.
  772. * Linker libraries:                     Background.
  773. * Making efficient calls:               Using inlines.
  774. * New inlines format:                   New format.
  775. * Old inlines format:                   Old format.
  776. * Other parsers:                        Authors.
  777. * Preprocessor symbols:                 Using inlines.
  778. * Rebuilding:                           Rebuilding.
  779. * Reporting bugs:                       Authors.
  780. * Source code:                          Rebuilding.
  781. * Stubs inlines format:                 Stubs format.
  782. * Usage:                                Usage.
  783. * Using FD2Inline:                      Using fd2inline.
  784. * Using inlines:                        Using inlines.
  785. * Varargs functions:                    Background.
  786. * Varargs problems:                     Old format.
  787. * What FD2InLine is:                    Introduction.
  788. * What has changed:                     History.
  789. * Where to put it:                      Installation.
  790.  
  791.  
  792. 
  793. Tag Table:
  794. Node: Top400
  795. Node: Introduction1054
  796. Node: Installation2243
  797. Node: Usage3659
  798. Node: Using inlines3927
  799. Node: Using fd2inline6775
  800. Node: Rebuilding10900
  801. Node: Internals13110
  802. Node: Background13496
  803. Node: Old format16149
  804. Node: New format20036
  805. Node: Stubs format24073
  806. Node: History24742
  807. Node: Authors26304
  808. Node: Index28408
  809. 
  810. End Tag Table
  811.